When an application saves data to a datafile using the cluster-write or cluster-replace primitives, the data is not necessarily written to disk immediately. It is placed in a buffer in memory, and only when the buffer becomes full is the data copied to disk and the buffer emptied. This is a common practice in all file management software, since it improves performance by minimizing the number of times that the disk is accessed. However, it also means that your datafile is not up-to-date until the file buffer is emptied (i.e. flushed) to disk.
The primitives db-get-flush and db-set-flush allow you to flush the datafile's buffer after every primitive that changes the datafile.
The following method flushes a datafile窶冱 buffer after adding a new cluster:
If your application crashes due to a power failure, hardware failure, or software bug, after calling either cluster-write or cluster-replace, but before the buffer was flushed, then the most recent data you attempted to store would not actually be safely saved in the datafile on the disk. It is also possible that the last byte written to disk was not the very end of a cluster; therefore, the datafile would be corrupted if the application unexpectedly terminated.
As a safety precaution, we recommend you call the db-flush primitive in your applications, to explicitly flush the datafile窶冱 buffer on demand. This primitive must be supplied with the database id number (DB id # in the previous example). It will flush the contents of a datafile窶冱 buffer on to disk and return an error number indicating whether or not the primitive succeeded or failed. The best time to call db-flush is immediately after a call to either cluster-write or cluster-replace.
Note that it is not necessary to call db-flush for a datafile that is open in Shared mode. The data buffer of a shared datafile is automatically flushed after every call to cluster-write and cluster-replace.
In an application, when new clusters are added to the datafile to build it up, they are placed within the datafile wherever adequate room is found for the cluster窶冱 data. In most cases, new clusters are added to the end of the existing datafile. However, sometimes empty space is made available within the body of the datafile - usually the result of replacing an old cluster with a new one of a different size:
r If the new cluster is smaller than the old one, then the extra space is vacant and available for the next write to the datafile.
r If the new cluster is larger than the old one, then the new cluster is added to the end of the datafile and the space occupied by the old cluster is left vacant.
After awhile, all this vacant space can build up to a considerable size, and can be reclaimed by compacting the datafile.
The pockets of empty space as well as the space occupied by deleted clusters can be reclaimed by calling db-compact. This primitive must be supplied with the database id number (DB id# from previous examples) and will compact the datafile and return an error number, indicating whether or not the primitive succeeded.
